feat: deserialize responses into typed Pydantic models - #20

What changed

Fixes firstlanding#6266: every SDK method was annotated as returning a Pydantic model but returned a raw dict at runtime — no deserialization step existed. HttpClient.request() and SyncHttpClient.request() now accept an optional response_type and validate the JSON body through a cached pydantic.TypeAdapter. Generics (TypeVar + @overload) make the type flow to call sites; hand-written callers (auth.py, channels) that omit response_type keep raw-dict behavior. A bodyless 204 on an operation promising a typed body raises ValidationError at the call. Ships py.typed (verified present in the wheel) — without it mypy treated the whole package as untyped. Includes the regenerated SDK + contract tests from the companion generator PR; contract tests now assert concrete Pydantic classes.

sequenceDiagram
    participant C as Caller
    participant R as Generated resource method
    participant H as HttpClient.request
    participant X as httpx
    C->>R: installations.activate(id)
    R->>H: request(path, response_type=Installation)
    H->>X: HTTP request
    X-->>H: response
    alt status 204 and response_type set
        H-->>C: raises ValidationError as server omitted promised body
    else response_type set
        H->>H: TypeAdapter(Installation).validate_python(json)
        H-->>C: Installation instance
    else no response_type
        H-->>C: raw parsed JSON
    end

classDiagram
    class HttpClient {
        request(path, response_type) T
        request_raw(path) dict
    }
    class SyncHttpClient {
        request(path, response_type) T
        request_raw(path) dict
    }
    class TypeAdapterCache {
        _type_adapter(tp) TypeAdapter
    }
    HttpClient ..> TypeAdapterCache : validates via
    SyncHttpClient ..> TypeAdapterCache : validates via

Scope: backend-only (Python SDK runtime + generated code).

Risk: medium — runtime breaking change for SDK users doing dict access on responses (resp["id"] → resp.id); the SDK is at 0.1.1 with few consumers. Release should be a minor bump (0.2.0) with a changelog note. The validation surfaced and the companion PR fixed a latent typegen bug (object-field annotation shadowing) that made every Attachment.object value fail validation.

User impact: SDK responses become real Pydantic models — IDE autocomplete, validation, datetime coercion; mypy/pyright now type-check actual calls (verified with both).

Testing: red-first runtime tests (model / list[Model] / raw-dict / 204 both paths / ValidationError, both transports); 38 http_client tests total incl. new coverage of request assembly, token precedence, path-prefix, error parsing; 1,720 regenerated contract tests against Prism; harness + phx_channel suites; ruff clean. Full local suite: 1,799 passed.

Follow-ups: none in this repo. PyPI release timing is a separate decision.

🤖 Generated with Claude Code